﻿package de.gameduell.framework.modules
{
	import de.gameduell.framework.util.HashMap;
	
	import flash.events.Event;

	/**
	 * Problem:
	 * Almost all computers today are event-driven systems
	 * The main programming challenge is to quickly pick and execute the right code in reaction to an event
	 * The reaction depends both on the nature of the event and on the current context, that is, the sequence of past events in which the system was involved
	 * Traditional “bottom up approaches represent the context ambiguously by a multitude of variables and flags, 
	 * which results in code riddled with a disproportionate number of convoluted conditional branches (if-else or switchcase statements)
	 * 
	 * Results of "bottom up" approach (access shared dependencies over monolithic entry point)
	 * 1. create error prone, difficult to extend and excessively complex application code
	 * 2. each branching point requires evaluation of a complex expression.
	 * 3. switching between different modes requires modifying many variables, which all can easily lead to inconsistencies.
	 * 
	 * http://en.wikipedia.org/wiki/Event-driven_programming
	 * http://www.drdobbs.com/cpp/184401643
	 * http://www.accu-usa.org/Slides/samek0311.pdf
	 * http://ehiti.de/machine_objects/#Machine
 	 * 
	 * Solution:
	 * HSM (Hierarchical state machines) aka "Engine" 
	 * - provide a minimal and generic event-processor that you can use with any event queuing and dispatching mechanism.
	 * - a state (machine) can abstract away all possible event sequences and capture only the relevant ones.
	 * - inversion of control: required dependencies will be injected via events with embedded model
	 *	
	 * Other related documentation: 
  	 * http://de.wikipedia.org/wiki/Endlicher_Automat
	 * http://de.wikipedia.org/wiki/Dependency_Injection
	 * http://de.wikipedia.org/wiki/Inversion_of_Control
	 * http://www.ordix.de/ORDIXNews/1_2008/Java_J2EE_JEE/spring_web_flow.html
	 * http://mina.apache.org/introduction-to-mina-statemachine.html
  	 * http://www.ogre3d.org/wiki/index.php/Game_State_Manager
	 * http://www.jmonkeyengine.com/doc/com/jmex/game/state/GameState.html
	 * http://creators.xna.com/en-us/samples/gamestatemanagement
	 * 
	 * @author ftru
  	 **/	
	public interface IModule {

		/**
		 * store context references for internal use and child creation.
		 **/		
		function init(contextMap:HashMap):void;
		
		/**
		 * a event occurs
		 **/
		function handleEvent(command:Event = null):void;

		/**
		 * subFrames = count of frames to compensate time lag
		 * dt = integrated time interval 
		 **/
		function timerUpdate(subFrames:int, dt:Number):void;
		
		/**
		 * allow to unregister event listeners and views before it will be reomved
		 **/
		function release():void;
		
		/**
		 * broadcast event to all other modules
		 */
		function broadcastEvent(e:Event):void;

		
	}
}